.\" Written in VIM, obviously.
.TH TTHSUM 1 "28th June 2005" "Walter Doekes" "GNU/Linux"
.SH NAME
tthsum \- generates or checks TTH message digests

.SH SYNOPSIS
.B tthsum
[-bhmpvVw] [-c [file]] | [file...]

.SH DESCRIPTION
.B tthsum
generates or checks TTH checksums (roots of the Tiger/THEX hash tree).
The Merkle Hash Tree, invented by Ralph Merkle, is a hash construct
that exhibits desirable properties for verifying the integrity of
files and file subranges in an incremental or out-of-order fashion.
.B tthsum
uses the Tiger hash algorithm, by Ross Anderson and Eli Biham,
for both the internal and the leaf nodes.

The specification of the THEX algorithm is at:
 . 
.I http://www.open-content.net/specs/draft-jchapweske-thex-02.html

The specification of the Tiger hash algorithm is at:
 . 
.I http://www.cs.technion.ac.il/~biham/Reports/Tiger/

Normally
.B tthsum
generates checksums of all files given to it as parameters and prints
the checksums followed by the filenames. If, however,
.B -c
is specified, only one filename parameter is allowed. This file should
contain checksums and filenames to which these checksums refer, and
the files listed in that file are checked against the checksums listed
there. See option
.B -c
for more information.

If no file is specified data will be read from standard input.

.SS OPTIONS
.TP
.B -b
An md5sum compatibility option. It does absolutely nothing.
(md5sum uses -b to treat binary files differently from texts files.)

.TP
.B -c
Check tthsum of all files listed in
.I file
against the checksum listed in the same file. The actual format of that
file is the same as output of
.BR tthsum .
That is, each line in the file describes a file. A line looks like:

.B <TTH CHECKSUM>\  <FILENAME>

So, for example, if a file were created and its message digest
calculated like so:

.B echo foo > tth-test-file; tthsum tth-test-file

.B tthsum
would report:

.B A2MPPCGS5CPJV6AOAP37ICDCFV3WYU7PBREC6FY\  tth-test-file

See
.B NOTES
for more information on the digest file format.

.TP
.B -m
Use
.BR mmap (2)
instead of
.BR read (2)
to read the contents of the files to hash. Normally, using read is
cheaper. This all depends on system load, I/O speed, CPU speed,
L1 and/or L2 cache size and whatnot.

.TP
.B -p
Show the progress. Print (<COMPLETED>/<TOTAL>) every 10 MiB
on standard error while hashing. The numbers are in MiB.

.TP
.B -v
Be verbose. Print filenames when checking (with -c).

.TP
.B -w
Warn on improperly formatted lines when checking (with -c).

.TP
.B -h, -V
Print a small help text or the version, respectively, on standard out.
If an unknown combination of options is encountered, the small help
is printed on standard error and
.B tthsum
will return non-zero. 

.SH NOTES
.B tthsum
intentionally uses an interface identical to md5sum.

.B tthsum
uses BASE32 encoding consisting of the following characters:
.BR ABCDEFGHIJKLMNOPQRSTUVWXYZ234567 .
It will accept lower case letters in the digest input as well.

.B tthsum
does not accept long options such as
.BR --help .

A digest file format line looks like:
.BR <BASE32><SPACES><FILENAME><EOL> .
.B BASE32
is a 39 character long BASE32 encoded string.
.B SPACES
is a set of two spaces (0x20).
.B FILENAME
is the name of the file, encoded in UTF8 and with all control
characters (those below 0x20) encoded as \\xNN or \\C C-style
escapes. (The backslash is escaped as \\\\ as well. On Windows,
backslashes in paths will be translated to slashes for compatibility
with real operating systems.)
.B EOL
may be CRLF (\\r\\n), just plain LF (\\n) or even nothing at
end-of-file.

If you see warnings about an improper locale setup,
check your LANG and/or LC_CTYPE environment variables.
If these are not set properly,
.B tthsum
cannot represent
non-ASCII characters (those above 0x7F) in UTF8. See
.BR locale (1)
for more information or try to set LC_CTYPE to e.g. "en_US".

.SH AUTHOR

.B tthsum
and this manpage were written by Walter Doekes (walter@djcvt.net).
The hashing code was copied directly from DC++, an open source
peer-to-peer file sharing program by Jacek Sieka (jacek@creatio.se)
who had based the hashing code on the one used in
BCDC++ (a modified DC++) by Dustin Brody (blackclaw@parsoma.net).
After version 1.1.0, the hashing code from the Tiger hash authors
is used instead, to support big endian architectures and to remove
the need for C++ compilers and libraries.
The md5sum manpage, written by Juho Vuori (javuori@cc.helsinki.fi),
was used as a template. This manpage was proofread by Dustin Brody.

.SH "RETURN VALUE"

.B tthsum
returns 0 if no error occurred or, when checking a digest,
if at least one line is formatted properly and the TTHs of all properly
formatted lines match.
.B tthsum
returns 2 if an unknown combination of options is encountered.
In all other cases will
.B tthsum
return 1.

.SH "SEE ALSO"
.BR cksfv (1),
.BR md5sum (1),
.BR sha1sum (1)
